/*
 * Copyright (c) 2012-2017 Red Hat, Inc.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *   Red Hat, Inc. - initial API and implementation
 */
package org.eclipse.che.api.core.model.workspace;

import java.util.List;
import org.eclipse.che.api.core.model.machine.Machine;
import org.eclipse.che.api.core.model.machine.MachineStatus;
import org.eclipse.che.commons.annotation.Nullable;

/**
 * Defines a contract for workspace runtime.
 *
 * <p>Workspace has runtime when workspace is <b>running</b> (its {@link Workspace#getStatus()
 * status} is one of the {@link WorkspaceStatus#STARTING}, {@link WorkspaceStatus#RUNNING}, {@link
 * WorkspaceStatus#STOPPING}).
 *
 * <p>Workspace runtime defines workspace attributes which exist only when workspace is running. All
 * those attributes are strongly related to the runtime environment. Workspace runtime always exists
 * in couple with {@link Workspace} instance.
 *
 * @author Yevhenii Voevodin
 */
public interface WorkspaceRuntime {

  /**
   * Returns an active environment name. The environment with such name must exist in {@link
   * WorkspaceConfig#getEnvironments()}.
   */
  String getActiveEnv();

  /** Returns a workspace root folder. The base folder for the workspace projects. */
  @Nullable
  String getRootFolder();

  /**
   * Returns development machine only if its status is either {@link MachineStatus#RUNNING running}
   * or {@link MachineStatus#DESTROYING destroying}, otherwise returns null which means that machine
   * is starting or hasn't been started yet.
   *
   * <p>Returned machine used for extensions management. It is guaranteed that configuration of that
   * machine exists in the active environment.
   *
   * <p>There is a contract between this method and {@link #getMachines()} method, if this method
   * returns null then {@code getMachines()} method returns an empty list, if this method returns
   * dev-machine then {@code getMachines()} method result includes dev-machine.
   */
  @Nullable
  Machine getDevMachine();

  /**
   * Returns all the machines which statuses are either {@link MachineStatus#RUNNING running} or
   * {@link MachineStatus#DESTROYING}.
   *
   * <p>Returned list always contains dev-machine.
   */
  List<? extends Machine> getMachines();
}
